%% Modify the appearance of table entries
% by Jaromir Benes
%
% In this m-file, we look into how to customise the appearance of NaNs,
% Infs, and zeros in table data areas, and how to format subheadings and
% time series descriptions.

%% Clear Workspace

clear;
close all;
home;
irisrequired 8.20111003;

%% Create artificial data to be reported

range = qq(1991,1):qq(1994,4);
a = tseries(range,0.004);
b = tseries(range,0);
c = tseries(range,@rand);
c(range(1:4)) = NaN;
c(range(end-3:end)) = Inf;

%% Start new report

x = report.new('','dateformat=','YY:P','colWidth=',2.3,'headlinejust=','r');

%% Format NaNs and Infs
%
% You can change the default appearance of NaNs and Infs (which is a dash
% and an infinity sign) in tables using the options `'nan'` and `'inf'`,
% respectively. These two are options belonging to series; they are though
% inheribtable so you can set them e.g. at the level of the table (or the
% whole report).
%
% All table data are printed in the LaTeX math mode. This means that each
% time you want to use plain text, you should include the appropriate LaTeX
% command that displays a text string within a math mode. Most often, this
% will be `'\textnormal'` as below.

x.table('Zeros printed as other numbers','range=',range, ...
    'nan=','\textnormal{NA}','inf=','\textnormal{INF}');

    x.series('Series a',a);
    x.subheading('Subheading stretching into the data part of the table');
    x.series('Series b',b);
    x.series('Series c',c);

%% Format zeros and subheadings
%
% We change the appearance of entries that are exactly zeros. They will not
% be formatted as other numbers (resulting here in `'0.00'`) but replaced
% with `'0'` instead. Note that entries that are small enough to appear as
% zeros but not pure zeros remain unaffected by the option `'pureZero'`.
%
% Second, with switch the option `'stretch'` to false in the subheading
% <?stretch?> causing the text to be contained in the descriptive part of
% the table only and not stretchin into the data part. This may, of course,
% often result in an excessively wide table.
%
% Also, we change the typeface in which the subheading text is typeset
% using the option `'typeface'` <?typeface?>.

x.table('Pure zeros printed as 0','range=',range,'pureZero=','0');

    x.series('Series a',a);
    x.subheading('Subheading not stretching as much...', ...
         'stretch=',false, ... %?stretch?
         'typeface=','\scshape'); %?typeface?
    x.series('Series b',b);
    x.series('Series c',c);

%% Format zeros yeat another way
%
% We keep the pure zero entries displayed as `'0'`, and we display the
% numerically small entries (that would result in a zero appearance under
% the current numeric format options) as a text string `'tiny'`.
%
% We print the series `a` twice. The first row <?twodec?> has the default
% numeric format, which is two decimals. Under this format the numbers
% appear as if they were zeros (recall that the series is filled with
% 0.004), and hence will be replaced with `'tiny'`. The second row
% <?threedec?> is formatted to three decimals, in which case the numbers no
% longer appear zeros, and are printed as they are.

x.table('Zeros by appearance printed as "tiny"','range=',range, ...
    'pureZero=','0','printedZero=','\textnormal{tiny}');

    x.series('Series a',a); %?twodec?
    x.series('Series a again',a,'decimal=',3); %?threedec?
    x.subheading('Just subheading...');
    x.series('Series b',b);
    x.series('Series c',c);

%% Include two-line descriptions
%
% If you give two strings to describe a series <?cellstr?> (using a cellstr
% instead of a simple string for the first input argument) the series
% description takes two rows, with the first one stretching over the unit
% and mark columns, too.

x.table('Also zeros by appearance printed as 0', ...
    'range=',range,'units=','% P.A.');

    x.series('Series a',a);
    x.series({'Text for series b...','...stretched over two rows'},b);
    x.series('Series c',c);
    
%% Publish report to PDF
%
% Compile the report into a PDF named `'report_table_formats.pdf'`. The
% `open` command to open the PDF <?open?> may not work on some systems.

x.publish('report_table_formats.pdf','deletetempfiles=',false);

open report_table_formats.pdf; %?open?

%% Help on IRIS functions used in this m-file
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help report
%    help report/new
%    help report/table
%    help report/series
%    help report/subheading
%    help report/publish
